<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Otto</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="An enhanced event bus with emphasis on Android support">
    <link href="static/bootstrap-combined.min.css" rel="stylesheet">
    <link href="static/app.css" rel="stylesheet">
    <link href="static/app-theme.css" rel="stylesheet">
    <link href="http://fonts.googleapis.com/css?family=Roboto:400,300italic,100,100italic,300" rel="stylesheet" type="text/css">
    <!--[if lt IE 9]><script src="static/html5shiv.min.js"></script><![endif]-->
  </head>
  <body data-target=".content-nav">
    <header>
      <div class="container">
        <div class="row">
          <div class="span5">
            <h1>Otto</h1>
          </div>
          <div class="span7">
            <menu>
              <ul>
                <li><a href="#download" class="menu download">Download <span class="version-tag">Latest</span></a></li>
                <li><a href="http://github.com/square/otto" data-title="View GitHub Project" class="menu github"><img src="static/icon-github.png" alt="GitHub"/></a></li>
                <li><a href="http://square.github.io/" data-title="Square Open Source Portal" class="menu square"><img src="static/icon-square.png" alt="Square"/></a></li>
              </ul>
            </menu>
          </div>
      </div>
    </header>
    <section id="subtitle">
      <div class="container">
        <div class="row">
          <div class="span12">
            <h2>An enhanced <strong>event bus</strong> with emphasis on Android support</h2>
          </div>
        </div>
      </div>
    </section>
    <section id="body">
      <div class="container">
        <div class="row">
          <div class="span9">
            <h3 id="introduction">Introduction</h3>
            <p>Otto is an event bus designed to decouple different parts of your application while still allowing them
            to communicate efficiently.</p>
            <p>Forked from Guava, Otto adds unique functionality to an already refined event bus as well as specializing
            it to the Android platform.</p>

            <h3 id="usage">Usage</h3>
            <p>Otto is designed with Android-specific use cases in mind and is intended for use as a singleton
             (though that is not required). Create an instance of an event bus with
             <pre class="prettyprint">Bus bus = new Bus();</pre> Because a bus is only effective if it is shared, we
             recommend obtaining the instance through injection or another appropriate mechanism.</p>

            <h4>Publishing</h4>
            <p>Event publishing is the most important part of the bus as it allows you to tell subscribers that an
            action has occurred. An instance of any class may be published on the bus and it will only be dispatched to
            subscribers for that type.</p>
            <p>To publish a new event, call the <code>post</code> method:</p>
            <pre class="prettyprint">bus.post(new AnswerAvailableEvent(42));</pre>
            <p>Posting to the bus is a synchronous action so when program execution continues it is guaranteed that all
            subscribers have been called.</p>

            <h4>Subscribing</h4>
            <p>Subscription is the complement to event publishing&mdash;it lets you receive notification that an event
            has occurred. To subscribe to an event, annotate a method with <code>@Subscribe</code>. The method should
            take only a single parameter, the type of which will be the event you wish to subscribe to.</p>
            <p>To listen for the event published in the previous section we would need the following:</p>
            <pre class="prettyprint">@Subscribe public void answerAvailable(AnswerAvailableEvent event) {
    // TODO: React to the event somehow!
}</pre>
            <p>The name of the method can be anything you like. The annotation, single argument, and public accessor
            are all that is required.</p>
            <p>In order to receive events, a class instance needs to register with the bus. If <code>this</code> refers
            to an instance of the class in which the previous method was present, we can register using the
            following:</p>
            <pre class="prettyprint">bus.register(this);</pre>
            <p><strong>Registering will only find methods on the immediate class type.</strong> Unlike the Guava event
            bus, Otto will not traverse the class hierarchy and add methods from base classes or interfaces that are
            annotated. This is an explicit design decision to improve performance of the library as well as keep your
            code simple and unambiguous.</p>
            <p>Remember to also call the <code>unregister</code> method when appropriate. See the sample application,
            <a href="http://github.com/square/otto">available on GitHub</a>, for a complete example.</p>

            <h4>Producing</h4>
            <p>When subscribing to events it is often desired to also fetch the current known value for specific events
            (e.g., current location, active user, etc.). To address this common paradigm, Otto adds the concept of
            'Producers' which provide an immediate callback to any subscribers upon their registration.</p>
            <p>To create a producer, annotate a method with <code>@Produce</code>. The method should take no parameters
            and its return type will be used as the type of event for which it can produce initial values. If we are
            keeping track of the last answer event somewhere from above we can register to produce its initial
            value:</p>
            <pre class="prettyprint">@Produce public AnswerAvailableEvent produceAnswer() {
    // Assuming 'lastAnswer' exists.
    return new AnswerAvailableEvent(this.lastAnswer);
}</pre>
            <p>Producers, like subscribers, must also be registered:</p>
            <pre class="prettyprint">bus.register(this);</pre>
            <p>When registering, the producer method will be called once for each subscriber previously registered for
            the same type. The producer method will also be called once for each new method that subscribes to an event
            of the same type.</p>
            <p>You may only have one producer per event type registered at a time on a bus.</p>

            <h4>Thread Enforcement</h4>
            <p>Since at times it may be ambiguous on which thread you are receiving callbacks, Otto provides an
            enforcement mechanism to ensure you are always called on the thread you desire. By default, all interaction
            with an instance is confined to the main thread.</p>
            <pre class="prettyprint">// Both of these are functionally equivalent.
Bus bus1 = new Bus();
Bus bus2 = new Bus(ThreadEnforcer.MAIN);</pre>
            <p>If you are not concerned on which thread interaction is occurring, instantiate a bus instance with
            <code>ThreadEnforcer.ANY</code>. You can also provide your own implementation of the
            <code>ThreadEnforcer</code> interface if you need additional functionality or validation.</p>

            <h3 id="download">Download</h3>
            <p><a href="https://search.maven.org/remote_content?g=com.squareup&a=otto&v=LATEST" class="dl version-href">&darr; <span class="version-tag">Latest</span> JAR</a></p>
            <p>The source code to the Otto, its sample, and this website is <a href="http://github.com/square/otto">available on GitHub</a>.</p>

            <h4>Gradle</h4>
            <pre class="prettyprint">dependencies {
  compile 'com.squareup:otto:<span class="version">+</span>'
}</pre>

            <h4>Maven</h4>
            <pre class="prettyprint">&lt;dependency>
  &lt;groupId>com.squareup&lt;/groupId>
  &lt;artifactId>otto&lt;/artifactId>
  &lt;version><span class="version pln"><em>(insert latest version)</em></span>&lt;/version>
&lt;/dependency></pre>
            <p>Once you've installed Otto, add the following lines to your <code>proguard-project.txt</code> file:</p>
            <pre class="prettyprint">-keepattributes *Annotation*
-keepclassmembers class ** {
    @com.squareup.otto.Subscribe public *;
    @com.squareup.otto.Produce public *;
}</pre>
            <p>This ensures your annotated methods aren't removed by ProGuard.</p>

            <h3 id="contributing">Contributing</h3>
            <p>If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request.</p>
            <p>When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also make sure your code compiles by running <code>mvn clean verify</code>.</p>
            <p>Before your code can be accepted into the project you must also sign the <a href="http://squ.re/sign-the-cla">Individual Contributor License Agreement (CLA)</a>.</p>

            <h3 id="license">License</h3>
            <pre>Copyright 2013 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</pre>
          </div>
          <div class="span3">
            <div class="content-nav" data-spy="affix" data-offset-top="80">
              <ul class="nav nav-tabs nav-stacked primary">
                <li><a href="#introduction">Introduction</a></li>
                <li><a href="#usage">Usage</a></li>
                <li><a href="#download">Download</a></li>
                <li><a href="#contributing">Contributing</a></li>
                <li><a href="#license">License</a></li>
              </ul>
              <ul class="nav nav-pills nav-stacked secondary">
                <li><a href="1.x/otto/">Javadoc</a></li>
                <li><a href="http://stackoverflow.com/questions/tagged/otto?sort=active">StackOverflow</a></li>
              </ul>
            </div>
          </div>
        </div>
        <div class="row">
          <div class="span12 logo">
            <a href="https://squareup.com"><img src="static/logo-square.png" alt="Square, Inc."/></a>
          </div>
        </div>
      </div>
    </section>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
    <script src="static/bootstrap.min.js"></script>
    <script src="static/jquery.smooth-scroll.min.js"></script>
    <script src="static/jquery-maven-artifact.min.js"></script>
    <script src="static/prettify.js"></script>
    <script type="text/javascript">
      $(function() {
        // Syntax highlight code blocks.
        prettyPrint();

        // Spy on scroll position for real-time updating of current section.
        $('body').scrollspy();

        // Use smooth-scroll for internal links.
        $('a').smoothScroll();

        // Enable tooltips on the header nav image items.
        $('.menu').tooltip({
          placement: 'bottom',
          trigger: 'hover',
          container: 'body',
          delay: {
            show: 500,
            hide: 0
          }
        });

        // Look up the latest version of the library.
        $.fn.artifactVersion('com.squareup', 'otto', function(version, url) {
          $('.version').text(version);
          $('.version-tag').text('v' + version);
          $('.version-href').attr('href', url);
        });
      });
    </script>
  </body>
</html>
